home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / qlib56.zip / DISK.DOC < prev    next >
Text File  |  1992-12-12  |  29KB  |  791 lines
  1.     DISK / FILE routines look for specified files on your disk, or report
  2.     disk status.  Several QLIB disk/file subroutines return the following
  3.     error codes:
  4.  
  5.          1 = file name is a nul string
  6.          2 = file not found
  7.          3 = path not found
  8.          4 = too many open files
  9.          5 = access denied (file may be read-only or a subdirectory,
  10.                             or subdirectory not empty)
  11.          6 = handle invalid
  12.          8 = insufficient memory
  13.         19 = disk is write-protected
  14.     &HFFFF = input past end of file
  15.  
  16.  
  17.     File attributes may be combined.  Each bit of a file attribute means:
  18.  
  19.          0 = normal files
  20.          1 = read-only
  21.          2 = hidden files
  22.          4 = system files
  23.          8 = volume label (only one per disk - may not be
  24.                            reliable)
  25.         16 = subdirectories
  26.         32 = archive bit set
  27.  
  28.      Thus a file attribute of 18 is a hidden subdirectory (16 OR 2)
  29.  
  30.      Note that QLIB subroutines no longer require zero-terminated filenames.
  31.  
  32.      QLIB's Input/Output subroutines provide fast, flexible file handling,
  33.      replacing BASIC's clumsy functions.  These subroutines return an error
  34.      code in QLIB's DOSError flag if something went wrong.
  35.  
  36.      Summary of QLIB's file I/O subroutines:
  37.  
  38.      FOpen       Open an existing file
  39.      FCreate     Make a new file and open it for output
  40.      FClose      Close a file opened by FOpen or FCreate
  41.  
  42.      FGet1       Read one byte from a file opened by FOpen
  43.      FGet2       Read 2 bytes from a file opened by FOpen
  44.      FGet4       Read 4 bytes from a file opened by FOpen
  45.      FGet8       Read 8 bytes from a file opened by FOpen
  46.      FGet        Read from a file opened by FOpen to an array
  47.      FGetSTR     Read an ASCII string from a file opened by FOpen
  48.  
  49.      FPut1       Write one byte to a file
  50.      FPut2       Write 2 bytes to a file
  51.      FPut4       Write 4 bytes to a file
  52.      FPut8       Write 8 bytes to a file
  53.      FPut        Write data to a file directly from an array
  54.      FPutSTR     Write an ASCII string to a file
  55.      FPutCRLF    Write CR+LF to a file
  56.  
  57.      FSeek       moves the file pointer forward or backward in the file
  58.      FFlush      flushes the QLIB and DOS output file buffers
  59.  
  60.  
  61.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  62.  
  63.      Function: driveerror% = DiskWP (drive%)
  64.      object file: diskwp.obj
  65.  
  66.           DiskWP determines if a floppy disk is ready and whether it
  67.      is write protected or not.  Supports physical drives A: and B:.
  68.  
  69.      driveerror% returned by DiskWP is a BIOS error code:
  70.  
  71.                 0 = no error
  72.                 1 = invalid disk number
  73.                 2 = disk not readable (not formatted, or wrong type)
  74.                 3 = disk is write-protected
  75.               128 = drive not ready
  76.  
  77.      Example:
  78.           REM $INCLUDE: 'qlib.bi'
  79.           drive% = 0              ' drive A:
  80.                                   ' drive% = 1 for drive B:
  81.           driveerror% = DiskWP (drive%)
  82.           IF driveerror% THEN ... ' oops, problem
  83.  
  84.  
  85.  
  86.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  87.  
  88.      Subroutine: DotBAK (filename$)
  89.      object files: dotbak.obj ($asciiz.obj, strrchr.obj, strlen.obj)
  90.  
  91.           DotBAK changes the name of an existing filename.ext to
  92.      filename.BAK.  If filename.BAK already exists, it is deleted before
  93.      filename.ext is renamed.  DotBAK updates the DOSError flag in case of
  94.      errors.
  95.  
  96.      Example:
  97.           REM $INCLUDE: 'qlib.bi'   ' has function declaration for DOSError
  98.  
  99.           REM I want to save an old data file DATA.DAT as a backup file
  100.           REM before writing a new DATA.DAT file.
  101.  
  102.           filename$ = "DATA.DAT"
  103.           CALL  DotBAK (filename$)  ' change existing DATA.DAT to DATA.BAK
  104.           IF DOSError THEN ...      ' in case of errors
  105.  
  106.  
  107.  
  108.  
  109.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  110.  
  111.      Subroutine: DriveSpace(drv$, total&, free&, oops%)
  112.      object file: drvspace.obj
  113.  
  114.           Returns the amount of total and free space left on a given disk
  115.      drive.  The drive string may be any legal disk drive, or "@" (AT sign)
  116.      for the default drive, and must be at least one character long.  An
  117.      illegal drive or other error will cause oops% to be returned as -1.
  118.      Note that total& and free& are LONG integers.  Works with logical
  119.      devices up to 2,147 Megabytes.
  120.  
  121.      Example:
  122.           drv$="C:"
  123.            .
  124.            .
  125.           CALL DriveSpace(drv$, total&, free&, oops%)
  126.           IF oops% = -1 THEN
  127.                   PRINT "Invalid drive specification"
  128.                   ELSE
  129.                   PRINT "Free space on drive "; drv$; " is"; free&; "bytes."
  130.                   PRINT "Total space on drive "; drv$; " is"; total&; "bytes."
  131.           END IF
  132.  
  133.  
  134.  
  135.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  136.  
  137.      Subroutine: Exist(filename$, oops%)
  138.      object file: exist.obj ($asciiz.obj)
  139.  
  140.           Tells you if a given file already exists.  Returns an error code
  141.      if it doesn't, or -1 if it does.  The filename must not include any
  142.      "?" or "*" wildcard characters.
  143.  
  144.      Example:
  145.        filename$="QLIB.QLB"
  146.        CALL Exist(filename$, oops%)
  147.        IF oops% = -1 THEN PRINT "File already exists"
  148.        IF oops% = 0 THEN PRINT "Path exists"
  149.                                   ' Filename$ = "d:\path"
  150.        IF oops% = 2 THEN PRINT "Path found, file not found"
  151.        IF oops% = 3 THEN PRINT "Path or file not found"
  152.  
  153.  
  154.  
  155.  
  156.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  157.  
  158.      Subroutine: FClose(handle%)
  159.      object file: fopen.obj
  160.  
  161.          Closes a file opened by FOpen or FCreate.  Handle% is the file
  162.      handle returned by FOpen.  FClose updates the DOSError flag.
  163.  
  164.      Example:
  165.          CALL FClose(handle%)
  166.  
  167.  
  168.  
  169.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  170.  
  171.      Subroutine: FCopy(FromFile$, ToFile$)
  172.      object file: fcopy.obj (q$alloc.obj, q$error.obj)
  173.  
  174.           Copies a file from FromFile$ to ToFile$, and updates DOSError
  175.      with an error code if something went wrong.  FromFile$ and ToFile$
  176.      may not include any wildcard characters (such as * and ?).  FCopy
  177.      will destroy any previously-existing file named ToFile$ before
  178.      copying the file.
  179.  
  180.      Example:
  181.           REM $INCLUDE: 'qlib.bi'
  182.  
  183.           FromFile$ = "b:\qlib.lib"
  184.           ToFile$ = "c:\qb4\qlib.lib"
  185.           CALL FCopy(FromFile$, ToFile$)
  186.           IF DOSError THEN ...                ' check for errors
  187.  
  188.  
  189.  
  190.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  191.  
  192.      Function: handle% = FCreate(file$)
  193.      object file: fopen.obj ($asciiz.obj)
  194.  
  195.          Creates a new file and returns a handle for subsequent writing.
  196.      If the file already exists, it will be truncated to zero bytes by
  197.      FCreate.  FCreate updates DOSError.
  198.  
  199.      Example:
  200.          REM $INCLUDE: 'qlib.bi'
  201.          file$ = "anyold.dat"
  202.          mode% = 1                   ' access mode: write only
  203.          handle% = FOpen(file$)      ' first try to open an existing file
  204.          IF DOSError = 2 THEN
  205.             handle% = FCreate(file$) ' create a new file if "anyold.dat"
  206.                                      ' is not found
  207.          ENDIF
  208.  
  209.  
  210.  
  211.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  212.  
  213.      Subroutine: FFlush (handle%)
  214.      object file: fflush.obj (fseek.obj, q$error.obj)
  215.  
  216.           Flushes the QLIB and DOS file output buffers associated with
  217.      handle%.  The file must have been opened with QLIB's FOpen or FCreate
  218.      functions.  Flushing the file buffer protects against unintended system
  219.      failures such as power outages.  Any data written to the file before
  220.      calling FFlush will be safely written to the disk.  FFlush also updates
  221.      QLIB's DOSError flag.
  222.  
  223.      Example:
  224.        REM $INCLUDE: 'qlib.bi'
  225.        f$ = "anyold.fil"
  226.        handle% = FCreate (f$)
  227.        ' program writes data to the file
  228.        .
  229.        .
  230.        .
  231.        CALL FFlush (handle%)
  232.        IF DOSError THEN ...           ' check for errors
  233.  
  234.  
  235.  
  236.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  237.  
  238.      Subroutine: FGet(handle%, aSEG%, aPTR%, bytes%)
  239.      object file: fget.obj ($handle.obj, q$fget.obj, $fget.obj)
  240.  
  241.          Reads bytes% bytes of data from a file opened by FOpen and
  242.      loads the data into an array beginning at the address pointed to
  243.      by aSEG% and aPTR%.  FGet updates the DOSError flag in case of errors.
  244.      Bytes% may be as large as 32,767.  If you want to read more (up to
  245.      65,535 bytes) use a LONG integer bytes& instead of bytes%.
  246.  
  247.      Example:
  248.         REM $INCLUDE: 'qlib.bi'
  249.         DIM a(99)
  250.         bytes% = 200                                  ' 2 bytes per integer
  251.         file$ = "anyold.dat": mode% = 0               ' read-only
  252.         handle% = FOpen(file$, mode%)                 ' open file
  253.         aSEG% = VARSEG(a(0))                          ' start at beginning
  254.         aPTR% = VARPTR(a(0))
  255.         CALL FGet(handle%, aSEG%, aPTR%, bytes%)
  256.         IF DOSError THEN ...                          ' check for errors
  257.  
  258.      You can also declare FGet as a function to return the number of bytes
  259.      actually read from the file:
  260.  
  261.      Example 2:
  262.         REM $INCLUDE: 'qlib.bi'
  263.         REM  declare FGet as a function, allowing bytes to be either
  264.         REM  INTEGER or LONG
  265.         DECLARE FUNCTION FGet&(h%, s%, p%, b AS ANY)
  266.         DIM a(99)
  267.         bytes% = 200                                  ' 2 bytes per integer
  268.         file$ = "anyold.dat": mode% = 0               ' read-only
  269.         handle% = FOpen(file$, mode%)                 ' open file
  270.         aSEG% = VARSEG(a(0))                          ' start at beginning
  271.         aPTR% = VARPTR(a(0))
  272.         bytes& = FGet(handle%, aSEG%, aPTR%, bytes%)
  273.         IF DOSError THEN ...                          ' check for errors
  274.         IF bytes& <> 200 THEN ...
  275.  
  276.  
  277.  
  278.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  279.  
  280.      Subroutine: FGet1(handle%, n%)
  281.      object file: fget1.obj
  282.  
  283.      Subroutine: FGet2(handle%, n%)
  284.      object file: fget2.obj
  285.  
  286.      Subroutine: FGet4(handle%, n& [or n!])
  287.      object file: fget4.obj
  288.  
  289.      Subroutine: FGet8(handle%, n#)
  290.      object file: fget8.obj
  291.  
  292.         FGet[n] subroutines write a single data point to the file opened
  293.      by FOpen.  FGet1 is intended for character or short integer data,
  294.      FGet2 is for INTEGER data, FGet4 is for LONG or SINGLE data and
  295.      FGet8 is for DOUBLE, CURRENCY or QLIB's COMPLEX data.  Note that
  296.      SINGLE or DOUBLE data may be either IEEE format or Microsoft Binary
  297.      Format.  FGet subroutines update the DOSError flag in case of errors.
  298.  
  299.      Example:
  300.           REM $INCLUDE: 'qlib.bi'
  301.  
  302.           handle% = FOpen(file$,0)
  303.               .
  304.               .
  305.               .
  306.           CALL FGet4(handle%, n&)
  307.           IF DOSError THEN  ...            ' check for errors
  308.  
  309.  
  310.  
  311.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  312.  
  313.      Function: s$ = FGetSTR$(handle%)
  314.      object file: fgetstr.obj ($handle.obj, $fget.obj)
  315.  
  316.          FGetSTR reads an ASCII string of up to 4094 bytes from the file
  317.      associated with handle%.  FGetSTR updates the DOSError flag in case
  318.      of errors.
  319.  
  320.      Example:
  321.          REM $INCLUDE: 'qlib.bi'
  322.          mode% = 0                     ' read only
  323.          handle% = FOpen("input.dat", mode%)
  324.          IF DOSError THEN PRINT "Error opening file":END
  325.          WHILE NOT DOSError
  326.            s$ = FGetSTR(handle)
  327.            PRINT s$
  328.          WEND
  329.  
  330.  
  331.  
  332.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  333.  
  334.      Function: count% = FileCount(s$, attr%)
  335.      object file: findfile.obj ($asciiz.obj)
  336.  
  337.           Counts the number of files matching the filespec s$.  S$ may
  338.      include the wildcard characters * and ?.
  339.  
  340.      Example:
  341.        REM $INCLUDE: 'qlib.bi'
  342.        s$ ="*.*"        ' count all files in the current directory
  343.        attr% = 0        ' normal files only
  344.        count% = FileCount(s$, attr%)
  345.  
  346.  
  347.  
  348.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  349.  
  350.     Function: fseg% = FLoad (filename$)
  351.     object files: fload.obj (q$alloc.obj, q$error.obj, $asciiz.obj)
  352.  
  353.     FLoad reads a specified file into far memory, returning the segment
  354.     address of the memory block where the file is located.  If an error
  355.     occurs when reading the file, FLoad returns fseg% = 0.  QLIB's
  356.     DOSError flag is also updated (see DOSError in SYSTEM.DOC).
  357.     If no error occurred, DOSError returns 0; otherwise it returns an
  358.     MS-DOS error code.  If fseg% = 0 and DOSError = 0 then insufficient
  359.     far memory is available.  To release the memory allocated by this
  360.     function, use FreeMem(fseg%).  See DATA.DOC.
  361.  
  362.     Example:
  363.      REM $INCLUDE: '\qb4\qlib.bi'
  364.      filename$ = "\ramfont\italics.fnt"
  365.      iseg% = fload (filename$)
  366.      IF DOSError THEN
  367.          .
  368.          .
  369.          .              ; error handling code
  370.  
  371.  
  372.  
  373.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  374.  
  375.      Function: handle% = FOpen(file$, mode%)
  376.      object file: fopen.obj, $handle.obj
  377.  
  378.          FOpen opens an existing file for input, output or random I/O.
  379.      Access mode is 0 for read only, 1 for write only and 2 for read/write
  380.      access.  File$ is any valid file name.  Handle% is the file handle
  381.      returned by FOpen for use with subsequent input from or output to the
  382.      file.  When a file is opened by FOpen, the MS-DOS file pointer is
  383.      positioned at the start of the file.  Use FSeek to position the
  384.      pointer at the end of the file, for appending the file.  FOpen
  385.      updates the DOSError flag if there was a problem.
  386.  
  387.      Example:
  388.         REM $INCLUDE: 'qlib.bi'
  389.         File$ = "anyold.fil"
  390.         mode% = 0                     ' read only
  391.         handle% = FOpen(file$, mode%)
  392.         IF DOSError THEN ...          ' check for error
  393.  
  394.  
  395.  
  396.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  397.  
  398.      Subroutine: FPut(handle%, ArraySegment%, ArrayPointer%, bytes%)
  399.      object file: fput.obj ($handle.obj, q$fput.obj)
  400.  
  401.          Writes data directly from an array to a file.  The file must have
  402.      been opened by QLIB's FOpen in write or read/write mode, or by FCreate.
  403.      Up to 65,535 bytes may be written each time FPut is called; for more
  404.      than 32,767 bytes, use a LONG integer (bytes&) instead of bytes%.
  405.      FPut updates the DOSError flag if someting went wrong.
  406.  
  407.      Example:
  408.         REM $INCLUDE: 'qlib.bi'    ' FOpen and FCreate function declarations
  409.         DIM a&(599)                ' 600 long integers
  410.         .
  411.         .
  412.         .                          ' program establishes values of the data
  413.         filename$ = "longint.dat"
  414.         CALL DotBAK(filename$)     ' rename previous file to "longint.bak"
  415.         h = FCreate(filename$)     ' new "longint.dat"
  416.  
  417.         IF DOSError THEN PRINT "Can't open output file": GOTO FileError
  418.         s = VARSEG(a&(0)): p = VARPTR(a&(0)): n = 2400
  419.         CALL FPut(h, s, p, n)
  420.  
  421.  CloseFile:
  422.         CALL FClose(h)
  423.         .
  424.         .
  425.  
  426.  REM  jump here if there was a problem creating the file
  427.  FileError:
  428.         .
  429.         .
  430.  
  431.  
  432.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  433.  
  434.      Subroutine: FPut1(handle%, n%)
  435.      Subroutine: FPut2(handle%, n%)
  436.      Subroutine: FPut4(handle%, n& [or n!])
  437.      Subroutine: FPut8(handle%, n# [or n@])
  438.      object file: fput1.obj (q$fput.obj)
  439.  
  440.      Similar to FGet[], above, but writes data to the file.  The file
  441.      should have been opened with FOpen (write or read/write mode) or
  442.      by FCreate.  FPut[] subroutines leave an error code in the DOSError
  443.      flag if something went wrong.
  444.  
  445.      FPut1 writes a single byte or character
  446.      FPut2 writes a 2-byte INTEGER
  447.      FPut4 writes 4 bytes of data, such as a LONG or SINGLE value
  448.      FPut8 writes 8 bytes of data, such as DOUBLE or CURRENCY values
  449.  
  450.  
  451.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  452.  
  453.      Subroutine: FPutCRLF(handle%)
  454.      object file: fputcrlf.obj ($handle.obj, q$fput.obj)
  455.  
  456.      Subroutine: FPutSTR(handle%, s$)
  457.      object file: fputstr.obj ($handle.obj, q$fput.obj)
  458.  
  459.          FPutSTR writes a string to an output file, updating the DOSError
  460.      flag if something went wrong.  FPutSTR does not write CR+LF at the
  461.      end of the string; use FPutCRLF to write to the next line in the file.
  462.  
  463.      Example:
  464.          REM $INCLUDE: 'qlib.bi'
  465.          REM  I want to copy "input.dat" to "output.dat"
  466.          REM  while filtering out references to "stupid boss"
  467.  
  468.          stupid$ = "stupid boss"
  469.          inhandle = FOpen("input.dat", 0)                  ' read only
  470.          IF DOSError THEN PRINT "Error opening input file":END
  471.          outhandle = FOpen("output.dat", 1)                ' write only
  472.          IF DOSError THEN PRINT "Error opening output file":END
  473.          WHILE NOT DOSError
  474.            s$ = FGetSTR(inhandle)
  475.            IF DOSError GOTO EndOfFile
  476.            IF INSTR(s$, stupid$) = 0 THEN
  477.                 CALL FPutSTR(outhandle, s$)
  478.                 CALL FPutCRLF(outhandle)
  479.            ENDIF
  480.          WEND
  481. EndOfFile:
  482.          CALL FClose(inhandle)
  483.          CALL FCLose(outhandle)
  484.  
  485.  
  486.  
  487.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  488.  
  489.      Subroutine: FSeek(handle%, bytes&, seekmode%)
  490.      object file: fseek.obj ($handle.obj)
  491.  
  492.          Moves the file pointer from its present position forward or
  493.      backward in the file.  The file must have been opened by FOpen
  494.      or FCreate.  Bytes& is the number of bytes to move the pointer.
  495.  
  496.      Seekmode% = 0 if bytes& is absoute offset from start of file
  497.                = 1 if bytes& is signed offset from current file pointer
  498.                = 2 if bytes& is signed offset from end of file
  499.  
  500.      Example:
  501.          CALL FSeek(handle%, bytes&, seekmode%)
  502.  
  503.  
  504.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  505.  
  506.      Function: s& = FSize (handle%)
  507.      object file: fsize.obj (d$error.obj)
  508.  
  509.           Given a valid file handle returned by a QLIB FOpen
  510.      subroutine, FSize returns the size of the file.  Any DOS errors
  511.      are flagged by DOSError (see DOSError in SYSTEM.DOC).
  512.  
  513.      Example:
  514.          REM $INCLUDE: 'qlib.bi'
  515.          handle% = FOpen(file$, mode%)
  516.          IF DOSError THEN . . .       ' error control stuff
  517.          s& = FSize(handle%)
  518.          IF DOSError THEN . . .       ' error control stuff
  519.          
  520.  
  521.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  522.  
  523.      Function: d$ = GetDRIVE
  524.      object file: getdrive.obj
  525.  
  526.          Returns the default drive.
  527.  
  528.      Example:
  529.          REM $INCLUDE: 'qlib.bi'
  530.              .
  531.              .
  532.              .
  533.          drive$ = GetDRIVE
  534.          PRINT "The default drive is "; drive$
  535.          REM  drive$ includes the trailing colon, i.e., drive$ = "C:"
  536.  
  537.  
  538.  
  539.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  540.  
  541.      Function: sub$ = GetSUB(d$)
  542.      object file: getsub.obj ($asciiz.obj, strncpy.obj)
  543.  
  544.          Gets the current directory on disk d$.  To get the current
  545.      directory on the default drive, set d$ = "@".  If d$ specifies an
  546.      invalid drive, sub$ will be a nul string.  NOTE: d$ must be at least
  547.      one character long.
  548.  
  549.      Example:
  550.          REM $INCLUDE: 'qlib.bi'
  551.          d$ = "C:"
  552.          sub$ = GetSUB(d$)
  553.          IF sub$ = "" THEN PRINT d$ + " is not a valid drive"
  554.  
  555.  
  556.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  557.  
  558.     Subroutine: FindFirstMatch(file$, fAttr%, oops%)
  559.     Subroutine: FindNextMatch(oops%)
  560.     Subroutine: FindFileName(filename$, flen%)
  561.     Subroutine: FindFileAttr(fAttr%)
  562.     Subroutine: FindFileDate(month%, day%, year%)
  563.     Subroutine: FindFileTime(hour%, min%, sec%)
  564.     Subroutine: FindFileSize(lowword%, highword%)
  565.     object file: findfile.obj ($asciiz.obj)
  566.  
  567.          This group of subroutines may be used to search for files which match
  568.     a specified file name.  The specified file name may include drive and
  569.     path, and may also include the * and ? wildcards.  These subroutines may
  570.     be used to duplicate the DOS DIR command.
  571.  
  572.     A search attribute (fAttr%) may also be specified.  File attributes are
  573.     listed on the first page of this file.
  574.  
  575.     fAttr% may include more than one type of file.  For example, if
  576.     fAttr% = 2 + 8, FindFirst/NextMatch will search for hidden and system
  577.     files as well as normal files (normal files will always be found).
  578.     The actual file attribute of the matched file will be returned by
  579.     FindFileAttr.  Files returned may have a combination of attributes; for
  580.     example, if a file attribute returned by FindFileAttr is 18 ( = 2 + 16),
  581.     this file is a hidden directory.
  582.  
  583.     The file size returned by FindFileSize is in two parts.  Use the following
  584.     code to determine the file size:
  585.  
  586.     CALL FindFileSize(lowword%, highword%)  ' assumes file matched with
  587.                                             ' FindFirst/NextMatch, oops% <> 0
  588.     size& = CLNG(lowword%)
  589.     IF lowword% < 0 THEN size& = size& + 65536&
  590.     size& = size& + highword% * 65536&
  591.  
  592.     see examples on the next page
  593.  
  594.  
  595.     Example 1:
  596.          filename$ = SPACE$(12)             ' filename$ must be initialized
  597.                                             ' as a 12-byte (or longer) string
  598.                                             ' or the namelen% will be returned
  599.                                             ' as -1
  600.          FileSpec$ = "\qb4\*.bas"
  601.          fAttr% = 0                         ' search only for normal files
  602.          CALL FindFirstMatch(FileSpec$, fAttr%, oops%)
  603.          IF oops% = -1 THEN PRINT "FileSpec$ is a nul string"
  604.          IF oops% THEN PRINT "No matching files"
  605.          WHILE oops% = 0
  606.               CALL FindFileName(filename$, namelen%)
  607.               IF namelen% = -1 THEN PRINT "filename$ shorter than 12 bytes"
  608.               PRINT LEFT$(filename$, namelen%)
  609.               CALL FindNextMatch(oops%)
  610.          WEND
  611.          REM  FindFileName, FindFileAttr, FindFileDate, FindFileTime and
  612.          REM  FindFileSize will return usable results only after a successful
  613.          REM  (oops% = 0) call to FindFirstMatch or FindNextMatch.
  614.  
  615.     Example 2:
  616.          REM  In this example, we will print all subdirectories one
  617.          REM  level down from the root directory
  618.          filename$ = SPACE$(12)             ' filename$ must be initialized
  619.                                             ' as a 12-byte (or longer) string
  620.          fAttr% = 16
  621.          FileSpec$ = "\*.*"
  622.          CALL FindFirstMatch(FileSpec$, fAttr%, oops%)
  623.          IF oops% THEN PRINT "No files or subdirectories"
  624.          WHILE oops% = 0
  625.               CALL FindFileAttr(fAttr%)
  626.               IF fAttr% AND 16 THEN
  627.                    CALL FindFileName(filename$, namelen%)
  628.                    PRINT LEFT$(filename$, namelen%)
  629.               END IF
  630.               CALL FindNextMatch(oops%)
  631.          WEND
  632.  
  633.  
  634.  
  635.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  636.  
  637.     Subroutine: GetFileAttr(file$, attr%, oops%)
  638.     object file: fileattr.obj ($asciiz.obj)
  639.  
  640.          Returns the attribute of file$.  File$ must not include
  641.     any * or ? wildcards.  File attributes are listed on the first page
  642.     of this file.  Oops% is an MS-DOS error code if something went wrong,
  643.     or oops% = -1 if no problems were encountered.
  644.  
  645.     Example:
  646.          file$ = "c:\qb4\qlib.lib"
  647.          CALL GetFileAttr(file$, attr%, oops%)
  648.  
  649.  
  650.  
  651.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  652.  
  653.     Subroutine: KillFile(file$, oops%)
  654.     object file: killfile.obj ($asciiz.obj)
  655.  
  656.          KillFile deletes file$ from a disk with error trapping, avoiding
  657.     BASIC's ON ERROR.  Oops% = 0 if no error; MS-DOS error codes apply if
  658.     oops% <> 0.
  659.  
  660.     Example:
  661.          file$ = "oldfile.dat"
  662.          CALL KillFile(file$, oops%)
  663.  
  664.  
  665.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  666.  
  667.     Subroutine: KillSUB(sub$, oops%)
  668.     object file: killfile.obj ($asciiz.obj)
  669.  
  670.          KillSUB deletes subdirectory sub$ from a disk with error trapping,
  671.     avoiding BASIC's ON ERROR.  The subdirectory must be empty before it is
  672.     deleted.  Oops% = 0 if no error; MS-DOS error codes apply if oops% <> 0.
  673.  
  674.     Example:
  675.          sub$ = "C:\123"
  676.          CALL KillSUB(sub$, oops%)
  677.  
  678.  
  679.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  680.  
  681.     Subroutine: MakeSUB(sub$, oops)
  682.     object file: killfile.obj ($asciiz.obj)
  683.  
  684.       Creates a new subdirectory.  Oops% is an MS-DOS error code returned
  685.     by MakeSUB.  If oops% = 0 then no error was detected.
  686.  
  687.     Example:
  688.       sub$ = "\qb4\qlib"     ' make a new subdirectory for QLIB
  689.       CALL MakeSUB(sub$, oops%)
  690.  
  691.  
  692.  
  693.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  694.  
  695.     Subroutine: Rename(old$, new$, oops)
  696.     object file: rename.obj ($asciiz.obj)
  697.  
  698.          Changes filename old$ to new$, returning an MS-DOS error code.
  699.     Similar to BASIC's NAME function, but does not require ON ERROR
  700.     to trap errors.  You may use Rename to move a file from one directory
  701.     to another on the same disk.
  702.  
  703.     Example:
  704.          old$ = "demo.bas"
  705.          new$ = "demo.bak"
  706.          CALL Rename(old$, new$, oops)
  707.  
  708.  
  709.  
  710.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  711.  
  712.     Subroutine: SetDRIVE(d$)
  713.     object file: setdrive.obj
  714.  
  715.          Sets d$ as the default drive.  D$ may be any valid disk drive or
  716.     other logical device (such as a RAMdisk).
  717.  
  718.     Example:
  719.          d$ = "a:"           ' the drive specifier d$ may be upper or lower
  720.                              ' case and need not include the colon.
  721.          CALL SetDRIVE(d$)   ' drive A: is now the default drive
  722.  
  723.  
  724.  
  725.  
  726.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  727.  
  728.     Subroutine: SetFileAttr(file$, attr%, oops%)
  729.     object file: fileattr.obj ($asciiz.obj)
  730.  
  731.          Changes the file attribute of file$.  File attributes are
  732.     described on the first page of this file.  Oops% returned by this
  733.     subroutine is an MS-DOS error code (see first page of this file).
  734.     If all O.K. then oops% = -1.
  735.  
  736.     Example:  I want to make my QLIB.LIB file read-only
  737.  
  738.          REM  I start by getting the present attribute
  739.          file$ = "QLIB.LIB"
  740.          CALL GetFileAttr(file$, attr%, oops%)
  741.          IF oops% <> -1 THEN
  742.                 REM  Uh oh, something went wrong
  743.                   .
  744.                   .
  745.                   .
  746.          END IF
  747.  
  748.          REM  now I'll add the Read-only bit to the attribute
  749.          attr% = attr% OR 1
  750.          CALL SetFileAttr(file$, attr%, oops%)
  751.  
  752.  
  753.  
  754.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  755.  
  756.      Subroutine: SetFileDate(file$, month%, day%, year%, hour%, min%, sec%)
  757.      object file: setfdate.obj ($asciiz.obj)
  758.  
  759.           Sets file time/date stamp.  The year may be either a four digit
  760.      or two digit number  (e.g., either 1986 or just 86).  DOS will round
  761.      the seconds value off to the next lower even number.  If there is a
  762.      problem with the  filename, or if the file is read-only, the month will
  763.      be returned as -1.  Note that midnight is 24:00.  If hour%, minute% and
  764.      second% are all 0, then the file's time will not be displayed in a
  765.      directory list.
  766.  
  767.      Example:
  768.           file$ = "anyfile.dat"
  769.           CALL SetFileDate(file$, month%, day%, year%, hour%, min%, sec%)
  770.  
  771.  
  772.  
  773.  
  774.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  775.  
  776.     Subroutine: SetSUB(sub$, oops%)
  777.     object file: killfile.obj ($asciiz.obj)
  778.  
  779.          Changes the default subdirectory to sub$.  Oops% is an error
  780.     code returned to BASIC.
  781.  
  782.     SetSUB's error codes:
  783.  
  784.          oops% = 0         no error
  785.                  1         subdirectory name is a nul string
  786.                  3         path not found
  787.  
  788.     Example:
  789.          directory$ = "\qb4\lib"
  790.          CALL SetSUB(directory$, oops%)
  791.